# Message : Message communication

This module is a standard multi-process communication library that uses a message queue with boundaries. Multi packet messages are not merged, and each read and write guarantees message integrity.

This module is mainly used for EdgerOS system service and shared message between apps.

User can use the following code to import the message module.

var message = require('message');

# Support

The following shows message module APIs available for each permissions.

# Message Object

# message.send(pid, msg[, timeout])

• pid {Integer} Target process ID.
• msg {String} | {Object} Message to be send.
• timeout {Integer} Wait timeout in milliseconds. default: undefined means wait forever.
• Returns: {Integer} The number of bytes actually sent, negative error.

Set a message to target process specified by pid. The message can be a string or an object. If it is an object, the system discards all methods and passes the object to other process.

# Example

var process = require('process');

var child = process.spawn('./hello.js', ['./hello.js', '-a', 'abc']);

if (child > 0) {
  var msg = { id: 0, msg: 'aaaa' };
  message.send(child, msg);
}

# message.send(service, msg[, timeout])

• service {String} System service name.
• msg {String} | {Object} Message to be send.
• timeout {Integer} Wait timeout in milliseconds. default: undefined means wait forever.
• Returns: {Integer} The number of bytes actually sent, negative error.

Set a message to system service process specified by service. The message can be a string or an object. If it is an object, the system discards all methods and passes the object to other process.

# Example

var queryMsg = ...; // Build a query message.

message.send('test_service', queryMsg);

# message.recv([info[, timeout]])

• info {Object} Object for storing message information.
• timeout {Integer} Wait timeout in milliseconds. default: undefined means wait forever.
• Returns: {String} | {Object} {Buffer} Received message.

The info object contains the following members:

• pid {Integer} Transmitter process ID. User Mode does not include this member.
• perm {Integer} Transmitter permission.
• appid {Integer} EdgerOS App ID (negative means not EdgerOS App).
• service {Boolean} Whether transmitter is a service.
• signature {Boolean} Whether has a signature.

Receive a message from the message queue. message defaults use asynchronous mode, users must first call message.async(false) to convert to synchronous mode before using this method. Only allowed in the main task. You can use message.fd() to get the message file descriptor, use the iosched module to detect readable, writable asynchronous events. (not recommended!)

# Example

message.async(false); // convert to synchronous mode
var info = {};
var msg = message.recv(info);
if (msg) {
  console.log(msg, 'from:', info);
}

# message.flush()

Clear all unreceived packets in the message queue.

# message.async([enable])

• enable {Boolean} Whether to enable asynchronous mode. default: true.

Message defaults use asynchronous mode, if the user wants to use synchronous mode, they must first call message.async(true).

# Message Events

The message object inherits from the EventEmitter class. The following events are thrown in some specific situations in asynchronous mode.

# message

The current process receives a message. This event only allows in main task.

# Example

message.on('message', function(msg, info) {
  // ...
});